home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Complementary Applications 2004 February / SGI IRIX 6.5 Complementary Applications 2004 February.iso / dist / cde.idb / usr / dt / share / man / cat3 / pam_start.z.z / pam_start.z
Encoding:
Text File  |  2003-11-18  |  4.4 KB  |  207 lines
  1. .\" Sccs id goes here
  2. '\"macro stdmacro
  3. .\" Copyright (c) 1995, Sun Microsystems, Inc. 
  4. .\" All Rights Reserved
  5. .\" Don't forget to enter .IX index entries for each function.
  6. .nr X
  7. .TH pam_start 3 "19 October 1995"
  8. .SH NAME
  9. pam_start, pam_end
  10. \- authentication transaction routines for PAM
  11.  
  12. .SH SYNOPSIS
  13. .LP
  14. .B cc
  15. .RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
  16. .B \-lpam
  17. .RI "[ " "library" " \|.\|.\|. ]"
  18. .LP
  19. .nf
  20. .ft 3
  21. #include <security/pam_appl.h>
  22. .ft
  23. .fi
  24. .LP
  25.  
  26. .BI "int pam_start(const char *" "service" ,
  27. .BI "const char *" "user" ,
  28. .BI "const struct pam_conv *" "pam_conv" ,
  29. .BI "pam_handle_t " "**pamh");
  30.  
  31. .BI "int pam_end(pam_handle_t *" "pamh" ,
  32. .BI "int" " status" );
  33.  
  34. .SH DESCRIPTION
  35. .IX "pam_start" "" "\fLpam_start\fP \(em initiate authentication transaction"
  36. .B pam_start(\|)
  37. is called to initiate an authentication transaction.
  38. .B pam_start(\|)
  39. takes as arguments the name of the current service,
  40. .IR service,
  41. the name of the user to be authenticated,
  42. .IR user,
  43. the address of the conversation structure,
  44. .IR pam_conv,
  45. and the address of a variable to be assigned the authentication handle,
  46. .IR pamh.
  47. Upon successful completion, 
  48. .IR pamh
  49. will refer to a
  50. .B PAM
  51. handle for use with subsequent calls to the authentication library.
  52.  
  53. The pam_conv structure,
  54. .IR pam_conv,
  55. contains the address of the conversation function provided by the
  56. application.  The underlying service module invokes this function
  57. to output information to and retrieve input from the user.
  58. The
  59. .IR pam_conv
  60. structure has the following entries:
  61. .RS
  62. .PP
  63. .nf
  64. .ft 3
  65. struct pam_conv {
  66.         int     (\(**conv)();        /* Conversation function */
  67.         void    \(**appdata_ptr;    /* Application data */
  68. };
  69.  
  70. .ft 1
  71. .fi
  72. .RE
  73.     where
  74. .RS
  75. .PP
  76. .nf
  77. .ft 3
  78.         int conv(int num_msg,
  79.                 const struct pam_message **msg, struct pam_response **resp,
  80.                 void *appdata_ptr);
  81.  
  82. .ft 1
  83. .fi
  84. .RE
  85.  
  86. The function
  87. .B conv()
  88. is called by a service module to hold a PAM conversation with the application 
  89. or user.  For window applications, the application can create a new
  90. pop-up window to be used by the interaction.
  91. .PP
  92. The parameter
  93. .IR num_msg
  94. is the number of messages associated with the call.
  95. The parameter
  96. .IR msg
  97. is a pointer to an array of length
  98. .IR num_msg
  99. of the
  100. .IR pam_message
  101. structure.
  102. .PP
  103. The structure
  104. .IR pam_message
  105. is used to pass prompt, error message, or any text
  106. information from the authentication service to the application or user.
  107. The memory used by
  108. .IR pam_message
  109. should be allocated and freed by the PAM authentication service.
  110. The structure
  111. .IR pam_response
  112. is used by the authentication service to get the user's response back from
  113. the application or user.
  114. The storage used by
  115. .IR pam_response
  116. should be allocated by the application and freed by the PAM
  117. authentication service.
  118. The
  119. .IR pam_message
  120. structure has the following entries:
  121. .RS
  122. .PP
  123. .nf
  124. .ft 3
  125. struct pam_message{
  126.         int     msg_style;
  127.         char    \(**msg;
  128. };
  129. .ft 1
  130. .fi
  131. .RE
  132.  
  133. The
  134. .IR pam_response
  135. structure has the following entries:
  136. .RS
  137. .PP
  138. .nf
  139. .ft 3
  140. struct pam_response{
  141.         char    \(**resp;
  142.         int     resp_retcode;    /* currently not used, should be set to 0 */
  143. };
  144. .ft 1
  145. .fi
  146. .RE
  147. .PP
  148. The message style,
  149. .IR msg_style,
  150. can be set to one of the following values:
  151. .RS
  152. .PP
  153. .nf
  154. .ft 1
  155. .IP PAM_PROMPT_ECHO_OFF 26
  156. prompt user, disabling echoing of response
  157. .IP PAM_PROMPT_ECHO_ON 26
  158. prompt user, enabling echoing of response
  159. .IP PAM_ERROR_MSG 26
  160. print error message
  161. .IP PAM_TEXT_INFO 26
  162. print general text information
  163. .\"};
  164. .ft 1
  165. .fi
  166. .RE
  167.  
  168. .IR appdata_ptr
  169. is an application data pointer which is passed by the application
  170. to the PAM service modules.
  171. Since the PAM modules pass it back through the conversation function,
  172. the applications can use this pointer to point to any application-specific
  173. data.
  174.  
  175. .B pam_end(\|)
  176. is called to terminate the authentication transaction identified
  177. by 
  178. .IR pamh
  179. and to free any
  180. storage area allocated by the authentication module.
  181. The argument,
  182. .IR status,
  183. is passed to the
  184. .IR cleanup()
  185. function stored within the pam handle, and is used to determine
  186. what module specific state must be purged.  A cleanup function
  187. is attached to the handle by the underlying
  188. .B PAM
  189. modules through a call to
  190. .B pam_set_item(3)
  191. to free module specific data.
  192.  
  193. .SH "RETURN VALUES"
  194. .PP
  195. Refer to
  196. .B pam(3)
  197. for information on error related return values.
  198. .SH "SEE ALSO"
  199. .BR pam_authenticate (3),
  200. .BR pam_set_item (3),
  201. .BR pam_acct_mgmt (3),
  202. .BR pam_open_session (3),
  203. .BR pam_setcred (3),
  204. .BR pam_chauthtok (3),
  205. .BR pam_strerror (3),
  206. .BR pam (3)
  207.